Memory API Reference

The Memory API provides a provider-based abstraction for storing, retrieving, and managing application memory. Memory can be used for conversational context, user-specific information, preferences, application state, and other data that should persist beyond a single operation. This page documents the current Memory API and its relationship with agents, conversations, and Knowledge.

Overview

BindAI memory is built around memory records and interchangeable providers. Conceptually:

Application
    |
    v
Memory Provider
    |
    v
Memory Records

Different providers can store records in different backends while exposing a common memory interface.

Memory Records

The primary unit of stored memory is a MemoryRecord. A memory record can contain information such as:

Key
Value
Namespace
Type
Metadata
Importance
Access count
Last-accessed information
Expiration
Embedding
Score
Tags
Source
Relationships
Related keys
Creation and update timestamps

This allows memory to represent more than a simple conversation transcript.

Memory Providers

BindAI separates memory storage behind provider implementations. Current providers include:

InMemoryProvider
SQLiteMemoryProvider
PostgreSQLMemoryProvider
VectorMemoryProvider
PineconeMemoryProvider
ChromaMemoryProvider

Conceptually:

Memory API
    |
    +---- InMemory
    +---- SQLite
    +---- PostgreSQL
    +---- Vector
    +---- Pinecone
    +---- Chroma

The application can choose a provider appropriate for its storage and retrieval requirements.

Assigning Memory to an Agent

Memory can be attached when constructing an agent. For example:

from bindai_core import Agent

agent = Agent.builder().provider("openai:gpt-4.1-mini").memory(memory).build()

The exact behavior of memory during agent execution depends on how the memory instance is configured and how the application uses it. Do not assume that attaching a provider automatically turns every stored record into conversational history.

Memory Operations

The memory abstraction supports operations for managing records. Common operations include:

Set
Get
Search
Check existence
Delete
Clear

Conceptually:

memory.set(...)
memory.get(...)
memory.search(...)
memory.exists(...)
memory.delete(...)
memory.clear(...)

The exact arguments depend on the memory API and provider implementation.

Reading Memory

Applications can retrieve records from memory. A lookup may retrieve a specific record:

Memory
  |
  v
Get Record
  |
  v
MemoryRecord

Search operations can retrieve records matching a query or other provider-supported criteria. This makes memory suitable for both direct lookups and broader retrieval.

Writing Memory

Applications can store information as memory records. For example, an application may store:

User preferences
Important facts
Conversation-related information
Application state
Long-lived context
Derived information

Memory should contain information that is useful for future operations rather than every transient value produced during execution.

Namespaces

Memory records can be organized using namespaces. Conceptually:

Namespace: user-123
    |
    +---- preference
    +---- profile
    +---- history

Namespace: user-456
    |
    +---- preference
    +---- profile
    +---- history

Namespaces provide a useful isolation mechanism when multiple users, applications, or logical contexts share the same provider. Applications should choose namespace boundaries deliberately.

Metadata

Memory records can contain metadata. Metadata can describe information such as:

Source
Category
User or application context
Record type
Additional filtering attributes

Metadata can be used by providers and search operations where supported. Applications should keep metadata consistent if it will be used for filtering or retrieval.

Search and Retrieval

Memory providers can support searching records. Depending on the provider, retrieval may involve:

Direct key lookup
Metadata filtering
Text-oriented search
Vector similarity
Provider-specific search mechanisms

Vector-based memory providers can use embeddings to retrieve semantically related records. Memory retrieval should be kept separate from Knowledge retrieval when the information being searched has different ownership or lifecycle requirements.

Memory Results

Memory operations can return structured memory results. A MemoryResult can represent retrieved memory information and associated retrieval metadata. Applications should use the result abstraction rather than assuming every provider returns the same underlying storage object.

Memory Management

BindAI provides memory-management concepts for controlling how records evolve over time. Memory management can include operations such as:

Touching a record
Reinforcing important memory
Weakening memory
Applying decay
Promoting records
Forgetting records
Setting expiration
Clearing expiration

These operations support applications that want memory to evolve rather than remain permanently static.

Importance and Access

Memory records can contain importance and access information. For example:

Memory Record
     |
     +---- Importance
     |
     +---- Access Count
     |
     +---- Last Accessed

These attributes can help applications implement memory-management strategies. They can be used with promotion, decay, or forgetting policies where appropriate.

Expiration

Memory records can have expiration information. Applications can use expiration to prevent information from remaining available indefinitely. Expiration is useful for:

Temporary context
Short-lived preferences
Cached information
Time-sensitive application state

Applications should define expiration rules according to the sensitivity and expected lifetime of the information.

Tags and Relationships

Memory records can contain tags and relationship information. Conceptually:

Memory A
   |
   +---- related to ----> Memory B
   |
   +---- related to ----> Memory C

Relationships can help applications represent connected pieces of information. Tags provide another way to classify and organize records.

Serialization

Memory records may contain structured data that needs to be serialized for storage. Applications should prefer values that can be represented consistently by the selected provider. Provider-specific serialization behavior should be considered when storing complex Python objects.

Conversation Memory

Conversation memory is an application-level use of the Memory abstraction. It should not be assumed that every memory provider automatically stores the complete transcript of every agent interaction. A conversation system can use memory records to represent information from previous interactions. Conceptually:

Conversation
    |
    v
Memory Records
    |
    v
Future Retrieval

This distinction allows applications to decide what conversational information is worth retaining.

Session Isolation

Applications should isolate memory between users, conversations, or other logical sessions when required. Namespaces, keys, metadata, and separate provider instances can be used as part of an isolation strategy. For example:

User A
  |
  +---- Namespace A

User B
  |
  +---- Namespace B

The exact isolation mechanism depends on the selected provider and application architecture.

Memory and Agent Execution

Memory can be combined with agent execution. Conceptually:

User Input
    |
    v
Agent
    |
    +---- Memory Retrieval
    |
    v
Model Execution
    |
    v
Agent Result

Memory provides persistent information that the application can use alongside the current request. It should not be confused with the transient execution context used while an operation is running.

Memory vs Execution Context

Memory and execution context have different purposes.

Memory	Execution Context
Persistent or reusable information	Runtime state
Can outlive one operation	Exists during execution
Provider-backed	Execution-specific
Can be searched or retrieved	Used to coordinate current work

Execution context should not automatically be treated as persistent memory.

Memory vs Conversation History

Conversation history and Memory are related but distinct concepts. Conversation history represents messages exchanged during a conversation. Memory represents information deliberately stored for later retrieval or reuse. For example:

Conversation History
        |
        v
    Important Fact
        |
        v
      Memory

An application can choose to extract useful information from conversations and store it as memory.

Memory vs Knowledge

Memory and Knowledge solve different problems.

Memory	Knowledge
User/application-specific information	External or shared information
Dynamic context	Document and information retrieval
Long-lived application state	Knowledge sources
Preferences and remembered facts	Documents and indexed content

An agent can use both. For example:

User Question
     |
     +---- Memory
     |
     +---- Knowledge
     |
     v
    Agent
     |
     v
  Response

Memory in Workflows

Workflow-based applications can use Memory as a shared persistence layer where appropriate. Conceptually:

Workflow
   |
   +---- Agent
   |
   +---- Tool
   |
   +---- Memory

This can allow workflow operations to store and retrieve information across execution boundaries. The exact workflow integration depends on the installed workflow implementation.

Memory and Multi-Agent Systems

Multiple agents can use the same memory provider or separate memory instances. Shared memory can support collaboration:

             Memory
            /      \
           /        \
      Agent A      Agent B

However, shared memory requires deliberate namespace and access design. Not every agent should necessarily have access to every memory record.

Provider Selection

Different providers are appropriate for different environments.

In-memory

Useful for:

Development
Tests
Temporary applications

SQLite

Useful for:

Local applications
Small deployments
Persistent development environments

PostgreSQL

Useful for:

Server applications
Shared persistent storage
Production-oriented relational storage

Vector Memory

Useful when semantic retrieval is important.

Pinecone

Useful for managed vector-backed memory deployments.

Chroma

Useful for local or application-managed vector storage. Provider choice should consider persistence, scale, retrieval requirements, operational complexity, and deployment architecture.

Resource Management

Persistent providers may hold resources such as database or client connections. Applications should release provider resources when they are no longer required. For example:

memory.close()

Where supported, memory providers can also be used as context managers. Applications should follow the lifecycle requirements of the selected provider.

Clearing Memory

Memory providers support clearing stored records. Clearing can be useful for:

Tests
Conversation resets
User-requested deletion
Temporary environments
Data lifecycle management

Because clearing can be destructive, applications should apply appropriate authorization and confirmation for production systems.

Error Handling

Memory operations can fail because of:

Storage errors
Database connection failures
Invalid data
Provider configuration errors
Network failures
Missing records
External vector-store failures

Applications should handle provider failures according to the importance of memory to the current operation. For some applications, memory may be optional context. For others, failure to access memory may need to stop execution.

Performance

Memory retrieval should be designed around the amount and type of information being stored. Useful practices include:

Retrieve only relevant records.
Use namespaces appropriately.
Keep metadata consistent.
Avoid unnecessarily large values.
Use vector retrieval when semantic search is appropriate.
Apply expiration where information is temporary.
Avoid loading an entire memory store for every request.

Large memory stores may require provider-specific indexing and retrieval strategies.

Security

Memory can contain private or sensitive application information. Applications should:

Isolate users and sessions.
Restrict provider access.
Protect database credentials.
Avoid storing unnecessary sensitive data.
Apply appropriate retention policies.
Support deletion where required.
Protect memory retrieval from unauthorized access.

The memory layer should be treated as a data store with the same security considerations as other application persistence systems.

Testing

Memory providers should be tested independently from agents. Useful tests include:

Setting records
Getting records
Searching
Metadata filtering
Existence checks
Deletion
Clearing
Expiration
Relationships
Provider failures
Resource cleanup
Namespace isolation

Provider-specific integration tests should verify behavior against the actual storage backend.

API Accuracy

The current Memory API should not be described as a generic automatic conversation-history mechanism. This documentation intentionally avoids assuming APIs such as:

agent.memory = provider
memory.remember(...)
memory.recall(...)
memory.store_message(...)
memory.load_conversation(...)
memory.clear_conversation(...)

unless they are explicitly implemented by the installed BindAI version. The current architecture is based on memory providers and memory records, with agent integration through the supported agent configuration.

Best Practices

Choose a provider appropriate for the deployment.
Use namespaces to isolate logical memory scopes.
Store useful information rather than every transient value.
Keep Memory distinct from Knowledge.
Keep Memory distinct from runtime execution context.
Use metadata consistently.
Apply expiration to temporary information.
Protect stored data and provider credentials.
Test providers independently.
Release provider resources appropriately.
Design shared memory access carefully in multi-agent systems.

The Memory API works closely with:

Agent
MemoryRecord
MemoryResult
MemoryManager
MemoryRegistry
Memory providers
Knowledge
Workflow
Execution context

Together these components provide persistent, searchable application memory without tying agents to one storage backend.

Summary

The Memory API provides BindAI with a provider-independent abstraction for persistent application memory. The core architecture is:

Application
    |
    v
Memory Provider
    |
    v
MemoryRecord
    |
    v
Retrieval / Management

Current providers include in-memory, SQLite, PostgreSQL, vector, Pinecone, and Chroma implementations. Memory can support conversational context, user-specific information, preferences, application state, and other reusable information while remaining separate from Knowledge and transient execution context.

​Memory API Reference

​Overview

​Memory Records

​Memory Providers

​Assigning Memory to an Agent

​Memory Operations

​Reading Memory

​Writing Memory

​Namespaces

​Metadata

​Search and Retrieval

​Memory Results

​Memory Management

​Importance and Access

​Expiration

​Tags and Relationships

​Serialization

​Conversation Memory

​Session Isolation

​Memory and Agent Execution

​Memory vs Execution Context

​Memory vs Conversation History

​Memory vs Knowledge

​Memory in Workflows

​Memory and Multi-Agent Systems

​Provider Selection

​In-memory

​SQLite

​PostgreSQL

​Vector Memory

​Pinecone

​Chroma

​Resource Management

​Clearing Memory

​Error Handling

​Performance

​Security

​Testing

​API Accuracy

​Best Practices

​Related APIs

​Summary

Memory API Reference

Overview

Memory Records

Memory Providers

Assigning Memory to an Agent

Memory Operations

Reading Memory

Writing Memory

Namespaces

Metadata

Search and Retrieval

Memory Results

Memory Management

Importance and Access

Expiration

Tags and Relationships

Serialization

Conversation Memory

Session Isolation

Memory and Agent Execution

Memory vs Execution Context

Memory vs Conversation History

Memory vs Knowledge

Memory in Workflows

Memory and Multi-Agent Systems

Provider Selection

In-memory

SQLite

PostgreSQL

Vector Memory

Pinecone

Chroma

Resource Management

Clearing Memory

Error Handling

Performance

Security

Testing

API Accuracy

Best Practices

Related APIs

Summary